overlay#

The overlay modifier places a view on top of the modified view, creating a layered composition. This is useful for adding decorations, badges, shadows, visual indicators, or interactive elements such as buttons or loading spinners.

Type#

1overlay?: VirtualNode | {
2  alignment: Alignment
3  content: VirtualNode
4}

Parameters#

1. VirtualNode (Simple Form)#

Directly specifies the overlay view to be layered on top of the current view. The overlay is aligned to the center by default.

1<Image
2  imageUrl="https://example.com/avatar.png"
3  overlay={<Circle fill="black" opacity={0.2} />}
4/>

2. Object Form with Alignment#

Provides both the overlay content and a custom alignment for positioning.

Structure#

1{
2  alignment: Alignment
3  content: VirtualNode
4}

Alignment options:#

• "top" | "bottom" | "leading" | "trailing"
• "topLeading" | "topTrailing"
• "bottomLeading" | "bottomTrailing"
• "center"

Example – badge overlay in top trailing corner:#

1<Image
2  imageUrl="https://example.com/avatar.png"
3  overlay={{
4    alignment: "topTrailing",
5    content: <Circle 
6      fill="red"
7      frame={{
8        width: 10,
9        height: 10
10      }}
11   />
12  }}
13/>

Behavior#

• The overlay is drawn in front of the base view.
• The overlay respects the bounds of the base view unless clipped.
• Layout and size of the base view are unaffected by the overlay.

Common Use Cases#

• Adding notification badges
• Overlaying loading indicators
• Adding visual highlights or status icons
• Layering semi-transparent effects

Example – Overlay with Text#

1<Rectangle
2  fill="blue"
3  frame={{
4    width: 100,
5    height: 100
6  }}
7  overlay={{
8    alignment: "center",
9    content: <Text foregroundColor="white">Hello</Text>
10  }}
11/>

This renders a white "Hello" text centered on top of a blue rectangle.

Summary#